Download
FAQ
History
HomeHomeNext API
Search
Feedback
Divider

Web-Tier Security

The Web-tier security model used in this release of the J2EE platform is based on the Java Servlet specification. This specification can be downloaded from http://java.sun.com/products/servlet/download.html.

Your Web application is defined using a standard J2EE web.xml deployment descriptor. The deployment descriptor must indicate which version of the Web application schema (2.3 or 2.4) it is using, and the elements specified within the deployment descriptor must comply with the rules for processing that version of the deployment descriptor. For version 2.4 of the Java Servlet Specification, this is "SRV.13.3, Rules for Processing the Deployment Descriptor". For more information on deployment descriptors, see .

The deployment descriptor is used to convey the elements and configuration information of a Web application. Security in a Web application is configured using deploytool to set the following options. When the settings are entered in deploytool, they are saved to a web.xml deployment descriptor which is contained in the WAR. To view the generated deployment descriptor, select Descriptor Viewer from deploytool's Tools menu. Use the Security pane of deploytool to configure the following Security elements for a Web application WAR file. See Setting Security Requirements Using deploytool for more information on using deploytool to accomplish these tasks:

These elements of the deployment descriptor may be entered directly into the web.xml file, or created using an application deployment tool, such as deploytool. This document describes creating the deployment descriptor using deploytool.

Some elements of Web application security need to be addressed in the deployment descriptor for the Web server, rather than the deployment descriptor for the Web application. This information is discussed in Installing and Configuring SSL Support, Using Programmatic Security in the Web Tier, and Security Roles.

Protecting Web Resources

You can protect Web resources by specifying a security constraint. A security constraint determines who is authorized to access a Web resource collection, a list of URL patterns and HTTP methods that describe a set of resources to be protected. Security constraints can be defined using an application deployment tool, such as deploytool, or using a deployment descriptor.

If you try to access a protected Web resource as an unauthenticated user, the Web container will try to authenticate you. The container will only accept the request after you have proven your identity to the container and have been granted permission to access the resource.

Security constraints only work on the original request URI, not on calls made via a RequestDispatcher (which include <jsp:include> and <jsp:forward>). Inside the application, it is assumed that the application itself has complete access to all resources and would not forward a user request unless it had decided that the requesting user had access also.

Controlling Access to Web Resources

You can set up a security constraint using an application deployment tool, such as deploytool, or by coding the information directly into the deployment descriptor between <security-constraint></security-constraint> tags. When you define security constraints, you need to make sure you have addressed the following issues:

If, for example, we were to create a deployment descriptor for a simple application using deploytool, we would follow the steps in Setting Security Requirements Using deploytool.

Setting Security Requirements Using deploytool

To set security requirements for a WAR, select the WAR in the deploytool tree, then select the Security tabbed pane. In the Security tabbed pane, you can define how users are authenticated to the server and which users have access to particular resources.

  1. Choose the Authentication Method.
  2. Authentication refers to the method by which a client verifies the identity of a user to a server. The authentication methods supported in this release are shown below and are discussed in more detail in Authenticating Users of Web Resources. Select one of the following authentication methods from the Authentication Method list:

    1. None
    2. Basic
    3. Client Certificate
    4. Digest
    5. Form Based
    6. If you selected Basic or Digest authentication, click Settings to go to the User Authentication Settings dialog and enter the Realm Name. If you selected Form Based authentication, click Settings to enter the go to the User Authentication Settings dialog and enter the Realm Name, Login Page, and Error Page.

  3. Define a Security Constraint.
  4. In the Security Constraints section of the screen, you can define the security constraints for accessing the content of your WAR file. Click the Add button adjacent to the Security Constraints field to add a security constraint. Double-click the cell containing the Security Constraint to change its name. Each Security Constraint consists of:

    1. A Web Resource Collection, which describes a URL pattern and HTTP method pair that refer to resources that need to be protected.
    2. An Authorization Constraint, which is a set of roles that are defined to have access to the Web Resource Collection.
    3. A User Data Constraint, which defines whether a resource is accessed with confidentiality protection, integrity protection, or no protection.
  5. Define a Web Resource Collection for this Security Constraint.
  6. With the security constraint selected, click the Add button adjacent to the Web Resource Collections field to add a Web resource collection to the security constraint. A Web Resource Collection is part of a Security Constraint and describes a URL pattern and HTTP method pair that refer to resources that need to be protected. Double-click the cell containing the Web Resource Collection to edit its name.

  7. Edit the contents of the Web Resource Collection by selecting it in the list, then clicking the Edit button. The Edit Contents dialog box displays. Use it to add individual files or whole directories to the Web resource collection, to add a URL pattern, or to specify which HTTP methods will be governed by this Web Resource Collection.
    1. Select the files and directories that you want to the Web Resource Collection (WRC) in the top text field and then click the Add button to add them to the Web Resource Collection.
    2. Add URL patterns to the Web Resource Collection by clicking Add URL and entering the URL in the edit field.
    3. Specify which HTTP Methods are to be added to the Web application. The options are: Delete, Get, Head, Options, Post, Put, and Trace. You must select at least one of the HTTP methods.
    4. Click OK to return to the Security tabbed pane. The contents of the WRC display in the box beside the Edit button.
  8. Select the Network Security Requirement for this Security Constraint. The choices are None, Integral, and Confidential.
    1. Specify NONE when the application does not require a security constraint.
    2. Specify CONFIDENTIAL when the application requires that data be transmitted so as to prevent other entities from observing the contents of the transmission.
    3. Specify INTEGRAL when the application requires that the data be sent between client and server in such a way that it cannot be changed in transit.
    4. If you specify CONFIDENTIAL or INTEGRAL as a security constraint, that type of security constraint applies to all requests that match the URL patterns in the Web Resource Collection, not just to the login dialog. For further discussion on Network Security Requirements, see Using SSL to Enhance the Confidentiality of HTTP Basic and Form-Based Authentication

  9. Select which roles are authorized to access the secure application. In the Authorized Roles pane, click Edit to specify which defined roles are authorized to access this secure application.
  10. Select the role for which you want to authorize access from the list of Roles and click the Add button to add it to the list of Authorized Roles.

    If Roles have not been defined for this application, click the Edit Roles button and add the Roles for this application. If you add Roles in this fashion, make sure to select the Security Role Mapping tab and map the roles to the appropriate users and groups. For more information on Role Mapping, see Mapping Roles to Users and Groups.

  11. To add security specifically to a JSP page or to a servlet in the application, select the JSP page or servlet in the deploytool tree and select the Security tab. For more information on the options displayed on this page, see Declaring and Linking Role References.

The resulting deployment descriptor, which can be viewed by selecting the WAR file in the deploytool tree and then selecting Descriptor Viewer from the Tools menu, might look something like this:

<?xml version='1.0' encoding='UTF-8'?> 
<web-app 
      version="2.4" 
      xmlns="http://java.sun.com/xml/ns/j2ee"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
            http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd" 
      > 
   <display-name>SimpleWebWar</display-name> 
   <servlet> 
      <display-name>GreetingServlet</display-name> 
      <servlet-name>GreetingServlet</servlet-name> 
      <servlet-class>GreetingServlet</servlet-class> 
   </servlet>

         <!-- SECURITY-ROLE-REF -->
    <security-role-ref>
      <role-name>SimpleAppUser</role-name>
      <role-link>user</role-link>
    </security-role-ref>
  </servlet>
  <session-config>
    <session-timeout>30</session-timeout>
  </session-config>

<!-- SECURITY CONSTRAINT -->
   <security-constraint> 
      <display-name>SecurityConstraint1</display-name> 
      <web-resource-collection> 
         <web-resource-name>WRCollection1</web-resource-name> 
         <http-method>GET</http-method> 
      </web-resource-collection> 
      <web-resource-collection> 
         <web-resource-name>WRCollection2</web-resource-name> 
         <url-pattern>/WEB-INF/classes/GreetingServlet.class
            </url-pattern>
         <http-method>POST</http-method> 
         <http-method>GET</http-method>
      </web-resource-collection> 
      <auth-constraint> 
         <role-name>admin</role-name>
      </auth-constraint> 
      <user-data-constraint> 
         <transport-guarantee>
            CONFIDENTIAL
         </transport-guarantee>
      </user-data-constraint> 
   </security-constraint>

<!-- LOGIN AUTHENTICATION -->
  <login-config> 
      <auth-method>BASIC</auth-method> 
   </login-config>

<!-- SECURITY ROLES -->
 <security-role> 
      <role-name>user</role-name> 
   </security-role> 
   <security-role> 
      <role-name>mgr</role-name> 
   </security-role> 
   <security-role>
      <role-name>admin</role-name> 
   </security-role> 

</web-app> 

Authenticating Users of Web Resources

When you try to access a protected Web resource, the Web container activates the authentication mechanism that has been configured for that resource. With a Web Application selected in the deploytool tree, select the Security tabbed pane and select one of the following User Authentication Methods:

Configuring Login Authentication

You can set up login authentication using an application deployment tool, such as deploytool, or by coding the information directly into the deployment descriptor between <login-config></login-config> tags. To configure the authentication mechanism that the Web resources in a WAR will use, select the WAR in the deploytool tree, and select the Security tabbed pane, then proceed as follows:

The <form-login-page> element Login Page parameter provides the URI of a Web resource relative to the document root that will be used to authenticate the user. The login page can be an HTML page, a JSP page, or a servlet, and must return an HTML page containing a form that conforms to specific naming conventions (see the Servlet 2.4 specification for more information on these requirements). The Error Page parameter requires a URI of a Web resource relative to the document root that send a response when authentication has failed.

A Universal Resource Identifier (URI), is a globally unique identifier for a resource. A Universal Resource Locator (URL) is a kind of URI that specifies the retrieval protocol (http or https for Web applications) and physical location of a resource (host name and host-relative path).

In the Java Servlet specification, the request URI is the part of a URL after the host name and port. For example, in the URL http://localhost:8080/myApp/jsp/hello.jsp, the request URI would be /jsp/hello.jsp. The request URI is further subdivided into the context path (which decides which Web application should process the request) and the rest of the path that is used to select the target servlet.

Using SSL to Enhance the Confidentiality of HTTP Basic and Form-Based Authentication

Passwords are not protected for confidentiality with HTTP basic or form-based authentication, meaning that passwords sent between a client and a server on a non-protected session can be viewed and intercepted by third parties. To overcome this limitation, you can run these authentication protocols over an SSL-protected session and ensure that all message content is protected for confidentiality.

To configure HTTP basic or form-based authentication over SSL, specify CONFIDENTIAL or INTEGRAL as the Network Security Requirement on the WAR's Security page in deploytool. Specify CONFIDENTIAL when the application requires that data be transmitted so as to prevent other entities from observing the contents of the transmission. Specify INTEGRAL when the application requires that the data be sent between client and server in such a way that it cannot be changed in transit.

If you specify CONFIDENTIAL or INTEGRAL as a security constraint, that type of security constraint applies to all requests that match the URL patterns in the Web resource collection, not just to the login dialog.


Note: Good Security Practice: If you are using sessions, once you switch to SSL you should never accept any further requests for that session that are non-SSL. For example, a shopping site might not use SSL until the checkout page, then it may switch to using SSL in order to accept your card number. After switching to SSL, you should stop listening to non-SSL requests for this session. The reason for this practice is that the session ID itself was non-encrypted on the earlier communications, which is not so bad when you're just doing your shopping, but once the credit card information is stored in the session, you don't want a bad guy trying to fake the purchase transaction against your credit card. This practice could be easily implemented using a filter.


Using Programmatic Security in the Web Tier

Programmatic security is used by security-aware applications when declarative security alone is not sufficient to express the security model of the application. Programmatic security consists of the following methods of the HttpServletRequest interface:

These APIs allow servlets to make business logic decisions based on the logical role of the remote user. They also allow the servlet to determine the principal name of the current user.

For example, to use the isUserInRole("admin") method in your application, you need to do the following with deploytool:

  1. Select the Web component (servlet, in this case).
  2. Select the Security tab.
  3. In the Role names referenced in code pane, click Add.
  4. Enter admin in the Role name field.
  5. Select the available Role Link from the pull-down. The role names that appear in the Role links pull-down menu have previously been defined for the application. See Security Roles for information about defining role names for an application.

Creating the Login Form

The content of the login form in an HTML page, JSP page, or servlet for a login page should be as follows:

<form method="POST"  action="j_security_check" >
 <input type="text"  name= "j_username" >
 <input type="password"  name= "j_password" >
</form> 

See the Servlet 2.4 specification for additional information.

Protecting Web Resources

Many applications feature unprotected Web content, which any caller can access without authentication. In the Web tier, unrestricted access is provided simply by not configuring a security constraint for that particular request URI. It is common to have some unprotected resources and some protected resources. In this case, you will have security constraints and a login method defined, but it will not be used to control access to the unprotected resources. The user won't be asked to log on until the first time they enter a protected request URI.

In the Java Servlet specification, the request URI is the part of a URL after the host name and port. For example, let's say you have an e-commerce site with a browsable catalog you would want anyone to be able to access and a shopping cart area for customers only. You could set up the paths for your Web application so that the pattern /cart/* is protected, but nothing else is protected. Assuming the application is installed at context path /myapp,

A user will not be prompted to log in until the first time that user accesses a resource in the cart subdirectory.

To set this up, select the WAR file's Security tabbed pane in deploytool and,

  1. Add or select a Security Constraint.
  2. Add or select a Web Resource Collection.
  3. With the Security Constraint and Web Resource Collection selected, click the Edit button.
  4. Click the Add URL Pattern button to identify the URL pattern that is protected. Click OK.
  5. Select the HTTP Methods to be protected. Click OK.

When the WAR file is deployed, access to these resources will be protected.

Divider
Download
FAQ
History
HomeHomeNext API
Search
Feedback
Divider

All of the material in The J2EE 1.4 Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.